Constants

SEPARATOR

SEPARATOR = ','

ERROR_READ_ONLY

ERROR_READ_ONLY = 1

ERROR_NO_CONNECTION

ERROR_NO_CONNECTION = 2

ERROR_VALIDATE

ERROR_VALIDATE = 3

ERROR_SAVING

ERROR_SAVING = 4

SEARCH_ALL

SEARCH_ALL = 0

SEARCH_STRICT

SEARCH_STRICT = 1

SEARCH_PREFIX

SEARCH_PREFIX = 2

SEARCH_GROUPS

SEARCH_GROUPS = 4

TYPE_CONTACT

TYPE_CONTACT = 0

TYPE_RECIPIENT

TYPE_RECIPIENT = 1

TYPE_TRUSTED_SENDER

TYPE_TRUSTED_SENDER = 2

TYPE_DEFAULT

TYPE_DEFAULT = 4

TYPE_WRITEABLE

TYPE_WRITEABLE = 8

TYPE_READONLY

TYPE_READONLY = 16

Properties

$primary_key

$primary_key : string

Type

string — Name of the primary key field of this addressbook. Used to search for previously retrieved IDs.

$name

$name

$readonly

$readonly : bool

Type

bool — True if the addressbook is read-only.

$groups

$groups : bool

Type

bool — True if the addressbook supports contact groups.

$undelete

$undelete : bool

Type

bool — True if the addressbook supports restoring deleted contacts.

$list_page

$list_page : int

Type

int — The current page of the listing. Numbering starts at 1.

$page_size

$page_size : int

Type

int — The maximum number of records shown on a page.

$group_id

$group_id : null|string|int

Type

null|string|int — If set, addressbook-specific identifier of the selected group. All contact listing and contact searches will be limited to contacts that belong to this group.

$ready

$ready : bool

Type

bool — True if the addressbook is ready to be used. See rcmail_action_contacts_index::$CONTACT_COLTYPES

$coltypes

$coltypes : array

Type

array — Definition of the contact fields supported by the addressbook.

$date_cols

$date_cols : string[]

Type

string[] — A list of record fields that contain dates.

$export_groups

$export_groups : bool

Type

bool — True if the addressbook supports exporting contact groups. Requires the implementation of get_record_groups().

$searchonly

$searchonly : bool

Type

bool — True if the addressbook does not support listing all records but needs use of the search function.

$sort_col

$sort_col : string

Type

string — Contact field by which to order listed records.

$sort_order

$sort_order : string

Type

string — Whether sorting of records by $sort_col is done in ascending (ASC) or descending (DESC) order.

$vcard_map

$vcard_map : string[]

Type

string[] — vCard additional fields mapping

$deletable

$deletable

$db_name

$db_name

$db_groups

$db_groups

$db_groupmembers

$db_groupmembers

$vcard_fieldmap

$vcard_fieldmap

$db

$db : \rcube_db

Store database connection.

Type

rcube_db

$user_id

$user_id

$filter

$filter

$result

$result

$cache

$cache

$table_cols

$table_cols

$fulltext_cols

$fulltext_cols

$error

$error : ?array

Type

?array — Error state - hash array with the following fields: type, message

$type

$type

Methods

__construct()

__construct(object  $dbconn, int  $user, int  $type) : mixed

Object constructor

Parameters

object $dbconn

Instance of the rcube_db class

int $user

User-ID

int $type

Type of the address (1 - recipient, 2 - trusted sender)

Returns

mixed —

get_name()

get_name() : string

Returns addressbook name

Returns

string —

set_search_set()

set_search_set(mixed  $filter) : void

Sets a search filter.

This affects the contact set considered when using the count() and list_records() operations to those contacts that match the filter conditions. If no search filter is set, all contacts in the addressbook are considered.

This filter mechanism is applied in addition to other filter mechanisms, see the description of the count() operation.

Parameters

mixed $filter

Search params to use in listing method, obtained by get_search_set()

get_search_set()

get_search_set() : mixed

Getter for saved search properties.

The filter representation is opaque to roundcube, but can be set again using set_search_set().

Returns

mixed —

Search properties used by this class

set_group()

set_group(mixed  $group_id) : mixed

Sets/clears the current group.

This affects the contact set considered when using the count(), list_records() and search() operations to those contacts that belong to the given group. If no current group is set, all contacts in the addressbook are considered.

This filter mechanism is applied in addition to other filter mechanisms, see the description of the count() operation.

Parameters

mixed $group_id

Returns

mixed —

reset()

reset() : void

Reset saved results and search parameters

list_groups()

list_groups(?string  $search = null, int  $mode) : array

List all active contact groups of this source

Parameters

?string $search

Optional search string to match group name

int $mode

Search mode. Sum of self::SEARCH_*

Returns

array —

Indexed list of contact groups, each a hash array

get_group()

get_group(string  $group_id) : ?array

Get group properties such as name and email address(es)

Parameters

string $group_id

Group identifier

Returns

?array —

Group properties as hash array, null in case of error.

list_records()

list_records(array  $cols = null, int  $subset, bool  $nocount = false) : array

List the current set of contact records

Parameters

array $cols

List of cols to show, Null means all

int $subset

Only return this number of records, use negative values for tail

bool $nocount

True to skip the count query (select only)

Returns

array —

Indexed list of contact records, each a hash array

search()

search(mixed  $fields, mixed  $value, int  $mode, bool  $select = true, bool  $nocount = false, array  $required = []) : \rcube_result_set

Search contacts

Parameters

mixed $fields

The field name or array of field names to search in

mixed $value

Search value (or array of values when $fields is array)

int $mode

Search mode. Sum of rcube_addressbook::SEARCH_*

bool $select

True if results are requested, False if count only

bool $nocount

True to skip the count query (select only)

array $required

List of fields that cannot be empty

Returns

\rcube_result_set —

Contact records and 'count' value

count()

count() : \rcube_result_set

Count the number of contacts in the database matching the current filter criteria.

The current filter criteria are defined by the search filter (see search()/set_search_set()) and the currently active group (see set_group()), if applicable.

Returns

\rcube_result_set —

Result set with values for 'count' and 'first'

get_result()

get_result() : ?\rcube_result_set

Return the last result set

Returns

?\rcube_result_set —

Current result set or NULL if nothing selected yet

get_record()

get_record(mixed  $id, bool  $assoc = false) : \rcube_result_set|array

Get a specific contact record

Parameters

mixed $id

Record identifier(s)

bool $assoc

Enables returning associative array

Returns

\rcube_result_set|array —

Result object with all record fields

get_record_groups()

get_record_groups(mixed  $id) : array

Get group assignments of a specific contact record

Parameters

mixed $id

Record identifier

Returns

array —

List of assigned groups indexed by a group ID. Every array element can be just a group name (string), or an array with 'ID' and 'name' elements.

validate()

validate(array  $save_data, bool  $autofix = false) : bool

Check the given data before saving.

If input not valid, the message to display can be fetched using get_error()

Parameters

array $save_data

Associative array with data to save

bool $autofix

Try to fix/complete record automatically

Returns

bool —

True if input is valid, False if not.

insert()

insert(array  $save_data, bool  $check = false) : int|bool

Create a new contact record

Parameters

array $save_data

Associative array with save data

bool $check

Enables validity checks

Returns

int|bool —

The created record ID on success, False on error

update()

update(mixed  $id, array  $save_cols) : bool

Update a specific contact record

Parameters

mixed $id

Record identifier

array $save_cols

Associative array with save data

Returns

bool —

True on success, False on error

delete()

delete(array  $ids, bool  $force = true) : int|false

Delete one or more contact records

Parameters

array $ids

Record identifiers

bool $force

Remove record(s) irreversible (unsupported)

Returns

int|false —

Number of removed records

undelete()

undelete(array  $ids) : mixed

Unmark delete flag on contact record(s)

Parameters

array $ids

Record identifiers

Returns

mixed —

delete_all()

delete_all(bool  $with_groups = false) : int

Remove all records from the database

Parameters

bool $with_groups

Remove also groups

Returns

int —

Number of removed records

create_group()

create_group(string  $name) : array|false

Create a contact group with the given name

Parameters

string $name

The group name

Returns

array|false —

False on error, array with record props in success

delete_group()

delete_group(string  $group_id) : bool

Delete the given group and all linked group members

Parameters

string $group_id

Group identifier

Returns

bool —

True on success, false if no data was changed

rename_group()

rename_group(string  $group_id, string  $newname, string  $newid) : string|false

Rename a specific contact group

Parameters

string $group_id

Group identifier

string $newname

New name to set for this group

string $newid

New group identifier (if changed, otherwise don't set)

Returns

string|false —

New name on success, false if no data was changed

add_to_group()

add_to_group(string  $group_id, array|string  $ids) : int

Add the given contact records the a certain group

Parameters

string $group_id

Group identifier

array|string $ids

List of contact identifiers to be added

Returns

int —

Number of contacts added

remove_from_group()

remove_from_group(string  $group_id, array|string  $ids) : int

Remove the given contact records from a certain group

Parameters

string $group_id

Group identifier

array|string $ids

List of contact identifiers to be removed

Returns

int —

Number of deleted group members

refresh_search()

refresh_search() : mixed

Refresh saved search set after data has changed

Returns

mixed —

New search set

get_error()

get_error() : ?array

Returns the last error occurred (e.g. when updating/inserting failed)

Returns

?array —

Hash array with the following fields: type, message. Null if no error set.

close()

close() : mixed

Close connection to source Called on script shutdown

Returns

mixed —

set_page()

set_page(int  $page) : mixed

Set internal list page

Parameters

int $page

Page number to list

Returns

mixed —

set_pagesize()

set_pagesize(int  $size) : mixed

Set internal page size

Parameters

int $size

Number of messages to display on one page

Returns

mixed —

set_sort_order()

set_sort_order(?string  $sort_col, ?string  $sort_order = null) : mixed

Set internal sort settings

Parameters

?string $sort_col

Sort column

?string $sort_order

Sort order

Returns

mixed —

insertMultiple()

insertMultiple(\rcube_result_set  $recset, bool  $check = false) : array

Create new contact records for every item in the record set

Parameters

\rcube_result_set $recset

Recordset to insert

bool $check

True to check for duplicates first

Returns

array —

List of created record IDs

get_col_values()

get_col_values(string  $col, array  $data, bool  $flat = false) : array

Utility function to return all values of a certain data column either as flat list or grouped by subtype

Parameters

string $col

Col name

array $data

Record data array as used for saving

bool $flat

True to return one array with all values, False for hash array with values grouped by type

Returns

array —

List of column values

compose_display_name()

compose_display_name(array  $contact, bool  $full_email = false) : string

Compose a valid display name from the given structured contact data

Parameters

array $contact

Hash array with contact data as key-value pairs

bool $full_email

Don't attempt to extract components from the email address

Returns

string —

Display name

compose_list_name()

compose_list_name(array  $contact) : string

Compose the name to display in the contacts list for the given contact record.

This respects the settings parameter how to list contacts.

Parameters

array $contact

Hash array with contact data as key-value pairs

Returns

string —

List name

compose_search_name()

compose_search_name(array  $contact, string  $email = null, string  $name = null, string  $templ = null) : string

Build contact display name for autocomplete listing

Parameters

array $contact

Hash array with contact data as key-value pairs

string $email

Optional email address

string $name

Optional name (self::compose_list_name() result)

string $templ

Optional template to use (defaults to the 'contact_search_name' config option)

Returns

string —

Display name

compose_contact_key()

compose_contact_key(array  $contact, string  $sort_col) : string

Create a unique key for sorting contacts

Parameters

array $contact

Contact record

string $sort_col

Sorting column name

Returns

string —

Unique key

fulltext_sql_where()

fulltext_sql_where(mixed  $value, mixed  $mode, mixed  $col = 'words', mixed  $bool = 'AND') : mixed

Helper method to compose SQL where statements for fulltext searching

Parameters

mixed $value
mixed $mode
mixed $col
mixed $bool

Returns

mixed —

_count()

_count() : int

Count number of available contacts in database

Returns

int —

Contacts count

set_error()

set_error(int  $type, string  $message) : mixed

Setter for errors for internal use

Parameters

int $type

Error type (one of this class' error constants)

string $message

Error message (name of a text label)

Returns

mixed —

compare_search_value()

compare_search_value(string  $colname, string|array  $value, string  $search, int  $mode) : bool

Compare search value with contact data

Parameters

string $colname

Data name

string|array $value

Data value

string $search

Search value

int $mode

Search mode

Returns

bool —

Comparison result

convert_db_data()

convert_db_data(mixed  $sql_arr) : mixed

Convert data stored in the database into output format

Parameters

mixed $sql_arr

Returns

mixed —

convert_save_data()

convert_save_data(mixed  $save_data, mixed  $record = []) : mixed

Convert input data for storing in the database

Parameters

mixed $save_data
mixed $record

Returns

mixed —

unique_groupname()

unique_groupname(string  $name) : string

Check for existing groups with the same name

Parameters

string $name

Name to check

Returns

string —

A group name which is unique for the current use